Introduction

Single Source is a solution to a common documentation problem: creating paper, Windows help and HTML documentation from a single source.  Many tools exist that would appear to do the job, but unlike Single Source they tend to be limited in the automatic creation of the following:

•	"What’s This?" help, obtained from low-level sections that have a particular heading style.

•	MAP file, allowing you to link a Help file to the application it documents.

•	Help Contents file, derived from the Table of Contents in the source document.

•	Related Topics list for each topic, derived from the primary keywords in the index terms for the topic.  When reading a topic in the Help file, you can click a button to display a list of topics that are related to it.

•	Hypertext links, derived from cross-references (for both Help and HTML).


Copyright Notice

All contents of the Single Source package are Copyright © 1999 Microdart Ltd, All Rights Reserved.  Copying and distribution of this product is strictly prohibited.


Disclaimer of Warranty and Liability

Use of Single Source indicates acceptance of the following, in which the Software refers to Single Source.

NO WARRANTIES

The author of the Software expressly disclaims any warranty for the Software. The Software and any related documentation is provided "as is" without warranty of any kind, either express or implied, including, without limitation, the implied warranties or merchantability, fitness for a particular purpose, or non-infringement. The entire risk arising out of use or performance of the Software remains with you.

NO LIABILITY FOR DAMAGES

In no event shall the author of the Software be liable for any damages whatsoever arising out of the use of or inability to use this product, even if the author of the Software has been advised of the possibility of such damages.


Ordering the Registered Version

This product is shareware.  If you find this product useful, you must register it.  The registration fee is ridiculously low when compared to competitors’ prices, but will nonetheless help to support future development.  So please keep to your part of the bargain.

In return, you will receive via Email or post (please specify) the registered version of the product, which incorporates the following useful (in our opinion, vital) functions:

•	Creation of an Index in the help file.  This comprises primary and secondary terms, as defined in XE fields.

•	Creation of Related Topics lists in the help file.  On clicking the Related button in the Help window, you are presented with a list of topics that have the same primary term(s) as the current topic.  With the unregistered version, this list is always empty.

•	Creation of a MAP file, allowing you to link an application to its Help.

To order your registered copy, please send a cheque or international money order for £25 (pounds sterling only), made payable to Microdart Ltd, to the following address:

Microdart Ltd, 17 Furze Lane, Purley, Surrey, CR8 3EJ, United Kingdom.


Tools Required

The following software is required to use Single Source:

•	Microsoft® Word 97 to create documents and to run the conversion macros.

•	Microsoft Help Workshop to compile Rtf files into Help.  You can download it from the following site:

http://support.microsoft.com/download/support/mslfiles/HCWSETUP.EXE


Single Source Files

Single Source comprises the following files:

•	SingleSource.dot, which contains the commands needed to process documents.

•	Paper.dot, the template for your paper documentation.

•	WindowsHelp.dot, the template for Help RTF files (only used behind the scenes).

•	SingleSource.doc, the paper documentation for Single Source.

•	SingleSource.hlp, the Help documentation for Single Source.

•	Contents.cnt, the Contents file for the Help documentation.

•	Standard HPJ, a template Help Project File used to compile Help from RTF files.


Performing the Installation

Installing the Templates

Copy the three template (.dot) files to your User Templates directory.  To find out where this is, choose Options from the Tools menu, then click the File Locations tab.

Installing the Application

If you don’t want Single Source to be automatically activated each time you start Word, do the following:

1.	Open MS Word.

2.	From the Tools menu, choose the Templates and Add-Ins option.

The Templates and Add-Ins dialog is displayed.

3.	Click the Add button.

4.	Locate and add the SingleSource.dot template.

In the list to the left, an entry for SingleSource.dot will be displayed and checked.

5.	To activate Single Source in a new Word session, open the Templates and Add-Ins dialog and tick the SingleSource entry.

Alternatively, if you want it to be automatically activated each time you start Word, simply copy the SingleSource.dot file to the Startup directory for Word.  To find out where this directory is, click Options on the Tool menu, then click the File Locations tab.


Strict Layout for Your Paper Documentation

You must use the Paper.dot template for any paper documentation.  This contains styles, which translate neatly into Windows help, and HTML.   Although you can change the styles in this template to better suit your requirements, remember that their treatment during conversion will remain the same.

The following sections explain the rules to which you should adhere in order for your paper documentation to be correctly converted into Windows help. For further guidance, examine the SingleSource.doc and ExampleGuide.doc files that come with this package.  It is recommended that you practice converting and compiling these files before attempting any of your own.

For examples of the use of each style, examine the SingleSource.doc and ExampleGuide.doc Word documents.

•	Use of Headings.

•	Use of Other Styles.

•	Index Terms.

•	Images.

•	Numbered Lists.

•	Cross-References.


Use of Headings

Style	Use
Heading 1	For the chapter titles in each subdocument of a master document.
Heading 2 & 3	To begin sections that you wish to appear as separate topics in the help file.  The converter begins a new topic at each such heading.
Heading 4	For sub-headings within a topic section.
Heading 5	For each sub-section documenting a control on a form.  These sub-sections are duplicated to create the context-sensitive or "What’s This?" topics for controls.  See the ExampleGuide document for an example of its use.


Use of Other Styles

Normal

Use the Normal style for an un-indented default paragraph, like this one.

Bullets and Bullets2

•	For bulleted lists, like this one.

•	Bullets gives a first-level bulleted list.

•	Bullets2 gives a second-level bulleted list.

Note: These styles do not include the actual bullets, which you must apply manually using the usual options.

Numbers and Continue Hang

1.	Use the Numbers style for a numbered list.

2.	Like this one.

Use the Continue Hang style to continue the hanging indent after a numbered item.  Or use it for any indented paragraph.

Note: The Numbers style does not include the actual numbers, which you must apply manually using the usual options.


Index Terms

To enter one or more index terms for entry in the paper and help indexes:

1.	Place the Insertion Point where you want the terms to be entered.  They are best placed at the end of Heading 2s and Heading 3s, just before the paragraph mark.  Note: Do not put index terms on a Heading 2 that is immediately followed by a Heading 3, since it is not converted into a topic.

2.	Either:

•	From the Insert menu, choose the Index Terms option.

•	Press Alt + I.

3.	In the displayed dialog, type the index terms, separating each with a semicolon.

4.	Click the OK button.

To view index entries, check the Hidden Text or All check box on the View tab of the Tools Options dialog.  They have the following format:

{ XE "primary term:secondary term" }

To enter just a primary term, simply omit the colon and secondary term.

The Registered version of Single Source uses these XE fields to create the following:

•	The help index, as displayed on the Index tab of the Help dialog.

•	Each topic’s list of Related Topics, which appears when you click the Related button on the Help dialog.  The list comprises those topics that have one or more primary index terms in common with the current topic.

Any secondary terms that you enter appear in both the paper and on-line index under their primary term, along with others that share the same primary term.


Images

You will probably want to insert images of the windows, dialogs, and controls in the software you are documenting.  It is recommended that you save these images as bmp files in order to reduce the size of your Word documents, thus improving performance.

To capture an image

1.	In the software being documented, display the image you want to capture.

2.	If the image is a resizable window, resize it to provide the best fit into the page-width of your paper documentation.

3.	Press Alt + Print Screen to capture the active window or dialog.

To save the image as a bitmap file:

1.	Open the Paint application supplied with Windows.

2.	From the Edit menu, choose Paste to paste you screen capture.

3.	From the Edit menu, choose Copy To.

The Copy To dialog is displayed.

4.	In the Save as type box, select 16 Color Bitmap.  This reduces the size of each bmp file, which can be important when documenting a large system.

5.	Enter the name and location of the file to which you want to save your image, then click the Save button.

To insert a stored image into a Word document

1.	In Word, from the Insert menu choose Picture: From File.

The Insert Picture dialog is displayed.

2.	Locate and select the bmp file you want to insert.

3.	If you don’t want the image to appear in the Help file, apply the Picture style to it.

4.	Resize the image as required to fit into the page-width.

Note: If the paragraph that precedes a Picture-style image ends with a colon (for example, "The Save window is displayed:") then this colon is removed during conversion, along with the image itself.


Numbered Lists

Numbered lists can cause many problems during help compilation.  The best solution is to manually enter the numbers instead of using the automatic numbered list facility.  However, if you have used the latter, you can convert the numbers to text by choosing the Convert Numbered Lists option from the Tools menu.  This is done automatically during conversion, but you may want to do it beforehand to check that the numbers are as you want.


Cross-References

Any cross-references you insert using the following method will be converted to hypertext links in the Help file.

1.	Enter text that contains the required reference to a heading (level 1, 2, or 3).  For example, "For details of the Save window, see Using the Save Window", where Using the Save Window is the exact text of the heading.

2.	In the text you have just entered, select the text of the heading; for example, "Using the Save Window".

3.	Either:

•	From the Insert menu, choose the Reference to Heading option.

•	Press Alt + R.

The selected text is italicised, and a page reference is inserted immediately after it, followed by a full stop which you may delete if not wanted.

Note: References must be italicised in order for the document to be correctly converted.


Labelling Blank Pages

It is traditional to put the words "This page is intentionally left blank" on any empty pages (even-numbered pages in a double-sided paper document).  This informs the reader that the blank page is not due to a printing error.

If you use these precise words, the converter will remove the words and the page automatically from the Help file.

To insert a blank page with this wording, choose the Intentionally Blank Page option from the Insert menu.


Inserting Examples of Reports

Many systems can produce reports based on information in their database.  It is useful for the user documentation to contain an example of each report, in an Appendix for example.  The following procedure is a good way to insert report images into a document.  It assumes that the system has the facility for exporting reports to rtf files.

1.	In the system being documented, produce a good example of the report.

2.	Use the system to export the report to an rtf file.

3.	In Word, from the Insert menu choose Object.

The Object dialog is displayed.

4.	On the Object dialog, select the Create From File tab.

5.	Click the Browse button to locate and insert the rtf file for the report.

The report appears as an object in the current document.

6.	Right click on the object.

7.	From the pop-up menu displayed, choose Document Object, Convert.

The Convert dialog is displayed.

8.	In the Object Type list box, select Microsoft Word Picture, then click OK.

9.	Resize the picture as required to fit on the page.

Note: You may find that some reports fit better on a landscape page.


Using a Master Document

Reasons for Use

If your documentation comprises a number of chapters, you should consider using a master document.  This will have the following benefits:

•	Simplifies the creation of the index and table of contents.

•	Allows you to use references to sections in other chapters.

•	Reduces the number of pages in each editable document, resulting in faster editing and reduced likelihood of crashes. (Word has a limit to the number of pages it can handle in a document).

•	Enables you to create one Help or HTML file for the whole document, with a reference to each chapter in the Table of Contents.

Procedure

1.	Create a separate document for each chapter of the manual, remembering to base it on the Paper template.  These will become the subdocuments of the master document.

2.	Create the master document based on the Guide template, and enter the title of the manual on the first line in the Heading 1 style.

3.	From the View menu, choose Master Document.

4.	Click the Insert Subdocument toolbar button to insert each subdocument in order.  Each time, click the No To All button on the displayed dialog.


Using Hidden Text

During conversion to the RTF file, you are asked if you want hidden text to appear in the help file.  This allows you to enter text in your paper document that you do not want to appear in the Help file, or vice versa.

If there is text that you want to appear in one format but not the other (e.g. paper but not help), format this text as Hidden.  To do this, select the text, open the Format Font dialog box and put a tick in the Hidden check box.

Including the hidden text in the paper document but not the Help

To print the document, choose the Print with Hidden option from the File menu. The document closes when printing has started.

When converting to Help, click the No button or press Enter when asked if you want to include hidden text in the Help.

Including the hidden text in the Help but not the paper document

When printing the document, click the Options button on the Print dialog, and ensure that the Hidden Text check box is cleared.

When converting to Help, click the Yes button when asked if you want to include hidden text in the Help.


Creating the Rtf File

To convert a document or master document into an Rtf file suitable for compiling:

1.	Open the document in Word.

2.	Remove text that is irrelevant to Windows Help.  This generally includes all material preceding the table of contents, such as the title page.

3.	From the Tools menu, choose the Convert Paper To Help option.

You are asked if you want to include hidden text in the help file.  For details, see Using Hidden Text.

4.	Click Yes to reveal any hidden text in your paper document so that it appears in the help.  Click No or press Enter to leave it hidden, so that it does not appear in the help.

After a short while, the Save As dialog is displayed.

5.	In the Save in box, locate the directory in which you want to save the help and its associated files.  Do not change any other information.

6.	Click the Save button to continue with the conversion to help.  If at this stage you want to cancel the process, click the Cancel button.

When conversion finishes, the Word document is closed.


Compiling the Rtf File

1.	Open the Microsoft Help Workshop application.

2.	Click the Open toolbar button, and open the standard HPJ file supplied with Single Source, or use your own alternative.

The HPJ file details are displayed.

3.	In the Help File box, enter the name you wish to give to the Help file.

4.	Click the Files button.

The Topic Files window is displayed.  This shows the Rtf files to be used to create the Help file.

5.	Click the Remove button to remove any unwanted files from the list.

6.	Click the Add button, and select the Rtf file(s) you wish to use.

7.	Choose File Save As and save the updated HPJ file in the same directory as the Rtf file.

8.	Click the Compile toolbar button [image].

The Compile a Help File dialog is displayed.

9.	Click the Compile button to begin compilation.

Any errors are displayed during compilation and also sent to the error.txt file in the save directory.

On completion, the Help file appears in the save directory.  With the registered version of Single Source, a text file called IDH also appears; this is the MAP file.  View this file to find out the Help Context Ids that must be entered in the documented application in order to refer to topics in the Help file.

All other files in the save directory were only needed during conversion and may be deleted if desired.


Summary of the Help Conversion Process

The following table summarises how Single Source uses various parts of your source documentation to create an Rtf file for help.

Creates this part of the help file	From these parts of the source document
Table of contents	Headings 1 (optional), 2 and 3.
Index (Note: Only created by the Registered version)	XE index fields
Primary help topics	Heading 2 and Heading 3 sections.  Note: A topic is not created for a Heading 2 that has no text (i.e. that is immediately followed by a Heading 3)
Hypertext jumps	Page references
What This? topics	Heading 5 sections
Related topics (Note: Only created by the Registered version)	Lists topics that have index keywords in common with the current topic
MAP file (for linking topics to the windows or controls they document.  Note: Only created by the Registered version)	Lists topics that have index keywords in common with the current topic
Table of Contents

On the Contents tab of the Help window, up to three levels of headings may appear.

When processing a master document, Heading 1s are automatically included, dividing the Help contents into chapters.

MAP File

Note: MAP files are only created when using the Registered version of the product.

The MAP file assigns a number (Help Context Id) to each topic in your help.  In application development environments such as Delphi and Visual Basic, these Ids can then be entered in the HelpContext properties of forms and controls.  This ensures that the appropriate topic is displayed when the user chooses to display the help for a particular control or form.

The converter creates the MAP file automatically.  Topics are numbered sequentially in increments of 10, starting at 10 for the first.

To make it easier to enter the Help Context Ids in the associated application or system, you can print the MAP file after successful compilation.  This is saved as a text file called IDH.txt in the same directory in which you chose to save the contents file.  Each entry in the file has the following format:

IDH_Topic Title=Help Context Id

For example, given the following entry:

IDH_Using the Save Dialog=190

you would probably want to enter the number 190 in the Help Context property of the Save dialog form.

HPJ File

You can base this on the one provided, which has the following properties.

Buttons: no default, all except Print and Options checked.

Macros: BrowseButtons(), CreateButton(btn_related,Related,ALink("contents")).  This creates the related topics button.


Troubleshooting Help Conversion

Any errors found in the Rtf file during compilation are listed in the Help Workshop window and also sent to the error.txt file in the Help directory.  Each error gives an error code and the topic number in which the error occurred.

To decode an error, look up its code (e.g. HC1010) in the Index of the Help Workshop help.

To locate the topic in which the error occurred, open the Rtf file, then either:

•	From the Edit menu, choose the Goto Help Topic option .

•	Press Alt +G.

In the dialog displayed, enter the topic number and then press Enter.  After a short while, the first line of the topic is displayed.


Converting to HTML

To convert the current document or master document to HTML, choose the Convert Paper to HTML from the Tools menu.

The following actions are performed:

•	Occurrences of "This page is intentionally blank" are removed.

•	Tables are centred.

•	Numbers in auto-numbered lists (as created with Numbering toolbar button) are converted to text numbers.

•	Images are restored to their original size.

•	The document is saved in HTML format, during which GIF files are created for each image in the document.

•	References, including the table of contents, are converted into hypertext links.  However, these are represented by an * in the HTML document.  To convert these into the text of the original reference, choose the Convert HTML References option on the Tools menu.

On completion, the save directory contains the HTML document and its associated GIF files.